Fox's Git Mirrors
docs/plugin-spec.md HEAD (ed7be254) Text, 9.85 KB
Plugin Specification — T383838plugin.toml
Version: 1.0.0
This document is the authoritative specification for Omegon plugin manifests. All plugins in the armory and third-party plugins must conform to this spec.
Overview
An Omegon plugin is a directory containing a T383838plugin.toml manifest and associated files. Plugins are installed via T383838omegon plugin install <uri> and managed through the CLI or TUI settings.
Manifest Structure
T383838[plugin] — Required
Every plugin must have a T383838[plugin] section with these fields:
┌─────────────┬──────────┬──────────┬──────────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├─────────────┼──────────┼──────────┼──────────────────────────────────────────────────────────┤
│ T383838type │ string │ ✅ │ One of: T383838persona, T383838tone, T383838skill, T383838extension │
│ T383838id │ string │ ✅ │ Reverse-domain identifier, e.g. T383838dev.styrene.omegon.tutor │
│ T383838name │ string │ ✅ │ Human-readable display name │
│ T383838version │ string │ ✅ │ Semantic version (e.g. T3838381.0.0) │
│ T383838description │ string │ ✅ │ One-line description, under 200 characters │
│ T383838authors │ string[] │ │ List of author names or handles │
│ T383838license │ string │ │ SPDX license identifier (e.g. T383838Apache-2.0, T383838MIT) │
│ T383838min_omegon │ string │ │ Minimum Omegon version required │
└─────────────┴──────────┴──────────┴──────────────────────────────────────────────────────────┘
ID convention: Use reverse-domain notation: T383838{tld}.{org}.{product}.{name}. Official plugins use T383838dev.styrene.omegon.*. Third parties use their own domain.
Version: Must follow Semantic Versioning 2.0.0.
T282828
[plugin]
type = "persona"
id = "dev.styrene.omegon.tutor"
name = "Socratic Tutor"
version = "1.0.0"
description = "Patient, skilled tutor — guides through questioning, never lectures"
authors = ["styrene-lab"]
license = "Apache-2.0"
min_omegon = "0.15.0"
T383838[persona] — Persona plugins only
T383838[persona.identity]
┌───────────┬────────┬──────────┬──────────────────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├───────────┼────────┼──────────┼──────────────────────────────────────────────────────────────────┤
│ T383838directive │ string │ ✅ │ Path to the behavioral directive markdown file (relative to plu… │
└───────────┴────────┴──────────┴──────────────────────────────────────────────────────────────────┘
The directive file (typically T383838PERSONA.md) must contain:
• A T383838# Title heading
• At least one behavioral principle section
• A "What NOT To Do" or equivalent anti-pattern section
T383838[persona.mind]
┌───────────────┬────────┬──────────┬───────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├───────────────┼────────┼──────────┼───────────────────────────────────────────┤
│ T383838seed_facts │ string │ │ Path to seed facts file (JSONL format) │
│ T383838seed_episodes │ string │ │ Path to seed episodes file (JSONL format) │
└───────────────┴────────┴──────────┴───────────────────────────────────────────┘
Seed facts format: One JSON object per line with these fields:
┌────────────┬──────────┬──────────┬───────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├────────────┼──────────┼──────────┼───────────────────────────────────────────┤
│ T383838section │ string │ ✅ │ Memory section (e.g. T383838Domain, T383838Constraints) │
│ T383838content │ string │ ✅ │ The fact content │
│ T383838confidence │ number │ ✅ │ Confidence score, 0.0–1.0 │
│ T383838source │ string │ │ Attribution for the fact │
│ T383838tags │ string[] │ │ Searchable tags │
└────────────┴──────────┴──────────┴───────────────────────────────────────────┘
T282828
{"section":"Domain","content":"CAP theorem: ...","confidence":0.95,"source":"brewer-2000","tags":["distributed","cap"]}
T383838[persona.skills]
┌────────────┬──────────┬──────────┬────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├────────────┼──────────┼──────────┼────────────────────────────────────────────┤
│ T383838activate │ string[] │ │ Skill plugin IDs or names to auto-activate │
│ T383838deactivate │ string[] │ │ Skill plugin IDs or names to deactivate │
└────────────┴──────────┴──────────┴────────────────────────────────────────────┘
T383838[persona.tools]
┌─────────┬──────────┬──────────┬───────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├─────────┼──────────┼──────────┼───────────────────────────────────────────────────────┤
│ T383838profile │ string │ │ Tool profile name to apply (e.g. T383838default, T383838restricted) │
│ T383838enable │ string[] │ │ Additional tools to force-enable │
│ T383838disable │ string[] │ │ Tools to force-disable │
└─────────┴──────────┴──────────┴───────────────────────────────────────────────────────┘
Valid tool names: T383838bash, T383838read, T383838write, T383838edit, T383838view, T383838web_search, T383838memory_store, T383838memory_recall, T383838memory_query, T383838design_tree, T383838design_tree_update, T383838openspec_manage, T383838cleave_assess, T383838cleave_run, T383838whoami, T383838chronos, T383838ask_local_model, T383838manage_ollama, T383838set_model_tier, T383838set_thinking_level, T383838manage_tools.
T383838[persona.routing]
┌──────────────────┬────────┬──────────┬─────────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├──────────────────┼────────┼──────────┼─────────────────────────────────────────────────────────┤
│ T383838default_thinking │ string │ │ Default thinking level: T383838off, T383838minimal, T383838low, T383838medium, T383838high │
└──────────────────┴────────┴──────────┴─────────────────────────────────────────────────────────┘
T383838[persona.tone]
┌─────────┬────────┬──────────┬────────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├─────────┼────────┼──────────┼────────────────────────────────────────────────────────┤
│ T383838default │ string │ │ Default tone plugin ID or name. Operator can override. │
└─────────┴────────┴──────────┴────────────────────────────────────────────────────────┘
T383838[persona.style]
┌──────────────┬────────┬──────────┬─────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├──────────────┼────────┼──────────┼─────────────────────────────────────────────────────┤
│ T383838badge │ string │ │ Emoji or short string shown in the dashboard footer │
│ T383838accent_color │ string │ │ Hex color for UI accents (e.g. T383838#2ab4c8) │
└──────────────┴────────┴──────────┴─────────────────────────────────────────────────────┘
T383838[tone] — Tone plugins only
┌───────────┬────────┬──────────┬──────────────────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├───────────┼────────┼──────────┼──────────────────────────────────────────────────────────────────┤
│ T383838directive │ string │ ✅ │ Path to the voice directive markdown file │
│ T383838exemplars │ string │ │ Path to exemplars directory (contains T383838.md files showing the voi… │
└───────────┴────────┴──────────┴──────────────────────────────────────────────────────────────────┘
The directive file (typically T383838TONE.md) should be under 2000 characters. Tones are injected into every response — brevity matters.
T383838[tone.intensity]
┌────────┬────────┬──────────┬───────────────────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├────────┼────────┼──────────┼───────────────────────────────────────────────────────────────────┤
│ T383838design │ string │ │ Intensity during design/creative work: T383838full (default), T383838muted, T383838off │
│ T383838coding │ string │ │ Intensity during coding/execution: T383838full, T383838muted (default), T383838off │
└────────┴────────┴──────────┴───────────────────────────────────────────────────────────────────┘
T383838[skill] — Skill plugins only
┌──────────┬────────┬──────────┬──────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├──────────┼────────┼──────────┼──────────────────────────────────────────┤
│ T383838guidance │ string │ ✅ │ Path to the skill guidance markdown file │
└──────────┴────────┴──────────┴──────────────────────────────────────────┘
The guidance file (typically T383838SKILL.md) must have a T383838# Title heading and at least one T383838## Section.
T383838[secrets] — Optional, any type
Secret declarations are names-only contracts. They tell Omegon which operator-managed secrets a plugin, skill, or tool may need, and which environment variables should be projected at runtime. Manifest authors must never put raw secret values in public Armory payloads.
┌──────────┬──────────┬──────────┬─────────────────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├──────────┼──────────┼──────────┼─────────────────────────────────────────────────────────────────┤
│ T383838required │ string[] │ │ Omegon secret names that must resolve for the plugin's normal … │
│ T383838optional │ string[] │ │ Omegon secret names that unlock optional behavior │
└──────────┴──────────┴──────────┴─────────────────────────────────────────────────────────────────┘
T383838[secrets.env]
T383838[secrets.env] maps environment variable names expected by external CLIs or tool runners to Omegon secret names:
T282828
[secrets]
required = ["VAULT_ROOT_TOKEN"]
optional = ["GITHUB_TOKEN"]
[secrets.env]
VAULT_TOKEN = "VAULT_ROOT_TOKEN"
GITHUB_TOKEN = "GITHUB_TOKEN"
This is the canonical way to express aliases such as "Vault CLI expects T383838VAULT_TOKEN, while the durable operator secret is stored as T383838VAULT_ROOT_TOKEN." Values may be plain secret names or balanced single-template references like T383838{VAULT_ROOT_TOKEN}. One-sided braces such as T383838{VAULT_ROOT_TOKEN or T383838VAULT_ROOT_TOKEN} are invalid. They must not be literal tokens, passwords, URLs with embedded credentials, or command output. Names-only schema validation is necessary but not sufficient; public Armory payload linting remains the second gate for obvious secret-shaped values.
T383838[tools.env]
Extension tools may scope env aliases to an individual tool:
T282828
[[tools]]
name = "vault_status"
description = "Check Vault status"
runner = "bash"
script = "tools/vault-status.sh"
[tools.env]
VAULT_TOKEN = "{VAULT_ROOT_TOKEN}"
Tool-level mappings override plugin-level mappings for the same env var. Omegon resolves the referenced secret through its secrets engine, registers the resolved value for redaction, and injects only the requested env vars into script, context, or container runners.
T383838[detect] — Optional, any type
File-signature-based auto-detection. When present, Omegon can suggest activating this plugin when matching files are found in a project.
┌───────────────┬──────────┬──────────┬────────────────────────────────────────────────────────────┐
│ Field │ Type │ Required │ Description │
├───────────────┼──────────┼──────────┼────────────────────────────────────────────────────────────┤
│ T383838file_patterns │ string[] │ │ Glob patterns to match (e.g. T383838*.kicad_pcb, T383838Cargo.toml) │
│ T383838directories │ string[] │ │ Directory names to match (e.g. T383838gerbers/, T383838src/) │
│ T383838default │ boolean │ │ If T383838true, this plugin is activated when no other plugin ma… │
└───────────────┴──────────┴──────────┴────────────────────────────────────────────────────────────┘
Detection is suggest-only — the operator must confirm activation. Once confirmed for a project, the choice persists in project settings.
Directory Layout
T282828
my-plugin/
├── plugin.toml # manifest (required)
├── PERSONA.md # persona directive (persona type)
├── TONE.md # tone directive (tone type)
├── SKILL.md # skill guidance (skill type)
├── mind/ # persona mind store
│ ├── facts.jsonl # seed facts
│ └── episodes.jsonl # seed episodes
├── exemplars/ # tone voice exemplars
│ └── *.md
├── skills/ # bundled skills (persona type)
│ └── sub-skill/
│ ├── plugin.toml
│ └── SKILL.md
└── README.md # human-readable description
Installation
T282828
# From git URL
omegon plugin install https://github.com/org/repo
# From git URL, specific subdirectory
omegon plugin install https://github.com/org/repo/personas/tutor
# From local path
omegon plugin install ./path/to/plugin
# List installed plugins
omegon plugin list
# Show plugin details
omegon plugin info <id>
# Remove a plugin
omegon plugin remove <id>
# Update from source
omegon plugin update <id>
Validation Rules
1. T383838plugin.type must be one of: T383838persona, T383838tone, T383838skill, T383838extension
2. T383838plugin.id must have at least 3 dot-separated segments
3. T383838plugin.version must be valid semver
4. T383838plugin.description must be non-empty and under 200 characters
5. All file paths in the manifest must resolve to existing files within the plugin directory
6. Plugin IDs must be unique across all installed plugins
7. Mind store JSONL lines must have T383838section, T383838content, and T383838confidence (0.0–1.0) fields
8. T383838TONE.md should be under 2000 characters
9. T383838PERSONA.md must include an anti-pattern section
10. Tool names in T383838disable/T383838enable must be recognized by the Omegon tool registry
11. Secret names and secret env aliases must be names only; raw secret values are forbidden in public payloads
Served by rngit 1.5.2 - Generated in 0.03s